 ___	      ___  ____		    Front end 0.26  (04 May 2006)
/ __)_ __ _ _(__ \|  _ \_ __  __ _  spr2png   0.25  (04 May 2006)
\__ \ '_ \ '_|/_/|  __/ '_ \/ _' | draw2spr  0.11  (04 May 2006)
(___/ .__/_| (___)|_|  |_| |_\__  | png2spr   0.08  (04 May 2006)
    |_|			     (___/   Darren Salt, 1998-2006


This program allows conversion of sprites to PNG files and Draw and Artworks
files to sprite or PNG, and the conversion of PNG files to sprites.

See the end of this file for distribution conditions, credits and copyrights.

These programs require RISC OS 3.50 or later (or at least support for deep
sprites), enough memory to store the image being processed in 32-bit RGB
colour.

If you plan to use this program to convert Artworks files, you should ensure
that you have the current release of AWViewer. This is available from
  http://www.mw-software.com/software/awmodules/awrender.html


CONTENTS
========

  The front end
  The back ends
  Known bugs
  Browser display of PNGs
  Licence
  Credits and copyrights
  Contact


The front end
=============

Conversion to PNG
-----------------

  Drag a sprite, Draw or Artworks file to the Spr2Png icon on the icon bar
  and a save box will appear. This contains the normal save box clutter and
  the following:

   [small sprite or PNG file icon]
      If the source is a Draw or Artworks file, this toggles the output type
      between sprite and PNG.

   Sprite
      The sprite source options.

     Image is RGBA
	If the sprite is 32-bit RGB colour, assume that it contains an alpha
	channel in the unused bits.

     Alpha channel is inverse
	Normally, the alpha channel scale ranges from 0 (transparent) to 255
	(opaque). This option tells Spr2Png that the reverse is true, ie.
	that 0 is opaque.

   Draw/AW
      The Draw and Artworks source options.

     Scale by
	This lets you arbitrarily scale the image by up to 10x along each
	axis. You may specify one scale factor in either field, or two
	independent scale factors; leave both fields blank for 1:1.
	Acceptable formats are simple, percentage and ratio; eg. to reduce to
	half size, you can use 0.5, 50% or 1:2.

     Artworks render level
	Controls how Artworks files are rendered. Useful values are:
	  0  - outlines only
	  5  - simple
	  10 - normal
	  11 - anti-aliased
	Note, however, that the image will be anti-aliased independently of
	the Artworks modules if an alpha channel is generated.

     Mask
     Alpha/blend
	These two options work together as follows:
	  Mask  Alpha	Effect
	   N	 N	No mask, no anti-aliasing (but see AW render level).
	   Y	 N	Simple mask, no anti-aliasing (ditto).
	   N	 Y	Background blended, always anti-aliased.
	   Y	 Y	Full alpha channel, always anti-aliased.

   Misc
      Options which don't fit elsewhere.

     Verbose
	The more ticks, the more info will be displayed as Spr2Png is
	processing an image.

     Single task
	Normally, the back end is run in a taskwindow. With this ticked, it's
	run in a command box instead (but without the full screen redraw).
	(Only available if the output is to a PNG.)

   Output
      Various output options.

     Interlaced
	An interlaced PNG will be created, using ADAM7 (the standard 2D
	interlacing for PNG files).
	(Only available if the output is to a PNG.)

     Trim masked edges
	Remove transparent rows and columns from around the edges of the
	output image. If there's no mask, then the background colour (if one
	is specified) is treated as transparent.

	For Draw and Artworks files, when no mask is to be output, this
	removes the same edge rows and columns since they would otherwise
	have been masked out.

     Background
	If you want to set a default background colour, then enter it in the
	writeable field next to this label. The format is 24-bit hex BBGGRR
	(ie. black=0, desktop blue=994400, bright green=FF00, white=FFFFFF).
	If you click on the button to the right, a colour picker dbox will be
	opened.

     Pixels per metre
     Pixel size
	For scaling purposes; useful if you started out with a
	rectangular-pixel sprite. Note that browsers tend to ignore these...

   Display
      Display information for applications which display PNG images.

     Gamma
	If you want the image to be displayed with gamma correction (provided
	that the program which is displaying it supports this), then enter a
	value here. The standard gamma value is 0.4545455 (more accurately,
	5/11 or 1/2.2).

    The remaining options in the Display section are probably best left
    alone. I know of no software which makes use of the information which
    these options provide.

     Render intent
	This sets the sRGB colourspace information. "Default" means that no
	sRGB information will be present in the output image; other values
	will override the gamma and chromaticity options.

       Set gamma & chromaticity
	  You can choose whether or not to embed corresponding gamma and
	  chromaticity information in the output image for use by
	  applications which don't understand sRGB and/or chromaticity
	  information.

     Chromaticity values
	Specifies chromaticity information for the image. There are four
	value pairs, for the image's white point and its red, green and blue
	channels: each value pair is a CIE x,y pair, with each element's
	value being between 0 and 1. (Appropriate defaults are set.)

   Reduce
      Image packing options, mostly affecting the actual image content.

     Try to make 8bit
	If possible, reduce the image to 8-bit colour.

       or less
	  ... or less, if the number of colours permits. This is best used
	  for images with long horizontal runs of the same colour; it can
	  also be used for greyscale images, unless an alpha channel is
	  present.

     sBIT chunk if true colour
	Counts the number of significant bits for the red, green and blue
	channels (for images which are or become 24 bit colour). This is
	recommended for 16bpp sprites.

     Extra greyscale checks
	Check whether only greys are used in an image. If so, then convert it
	to greyscale.

     Attempt to reduce mask
	If the mask is such that the image is fully opaque, ignore it.
	If the mask is simple and the resulting image would be 8-bit, use a
	spare palette entry for the mask.
	If the mask is such that the image is fully transparent... :-)

     Sort palette by usage
	Attempt to reduce the size of the PNG file by sorting the palette,
	most used colour first. The image is modified appropriately.

   Pack
      Compression options. These leave the image content intact.

     Filtering
	This lets you set the filtering options. Spr2Png will select from
	those chosen in order to best compress the image; see the libpng
	documentation for more details.

     Compression window
	This controls the maximum token size used by zlib (the compression
	code used by libpng). Higher values are almost always better (which
	is why the default is at the highest setting).

     Strategy
	The compression strategy. The default setting is normally the best,
	but 'filtered' (predictor) sometimes works better; if you want speed
	at the expense of size, then select Huffman or RLE (which may
	actually work better for certain images).

     Compression level
	How hard spr2png will try to compress the image. It is usually best
	to leave this set to 9 (as much as possible, at the expense of
	speed).

  It's recommended that you set a background colour; see the section on
  browser display for more details.

  When you select somewhere to save the file (permanently), the Spr2Png back
  end will be run in a taskwindow. It can be a bit memory-hungry, although
  this is entirely down to the requirement (well, it's *much* easier to code
  it that way) that it has the whole image in memory before conversion to PNG
  is begun.


  The sprite file format
  ----------------------

  The sprite file contaning the image to be converted may contain one or two
  sprites.

  The first sprite is the image to be converted, and may be of any depth and
  can have a palette. It may have a simple mask or an alpha mask.

  The second, if present, is used as an alpha channel: it must therefore be
  8bpp or less and have a standard greyscale palette. (If only the first and
  last colours are used - ie. full transparency and full visibility - then it
  is treated as a simple sprite mask.)

  If both sprites are present and the first one has a mask, then that mask is
  ignored.

  For <=8bpp sprites, palette packing is performed to reduce its size and try
  to improve the compression ratio. Normally, a logical colour (colour 0)
  will be allocated to the mask; if it is not possible to do this then the
  sprite will be scaled up to 24-bit (or 8-bit if it's greyscale) and be
  given an alpha channel.

  If an alpha channel is used, all non-greyscale sprites are scaled up to
  24-bit (15-bit sprites need to be scaled to 24-bit anyway).


Conversion from PNG
-------------------

  This requires RISC OS 3.50 or later; it normally generates 32-bit RGB
  colour sprites. (It does not yet generate sprites with Select-style alpha
  channels.)

  Drag a PNG to the Spr2Png icon on the icon bar and a different save box
  will appear. This contains the normal save box clutter and the following:

   Background
      When ticked, then the image will be blended onto the given background
      colour, or if none is given, onto the background colour specified in
      the PNG (or white if it doesn't specify one). No alpha channel is
      generated, but any present information will be used unless "Ignore
      transparency" is ticked.

      When unticked, then an alpha channel will be generated unless "Ignore
      transparency" is ticked.

      The button to the right of the writeable field will open a colour
      picker dbox will be opened, from which you can select a colour;
      otherwise, the format is 6 hexadecimal digits, interpreted as BBGGRR
      (ie. black=0, desktop blue=994400, bright green=FF00, white=FFFFFF).

   Image gamma
      When ticked, either the supplied gamma value or the image's own gamma
      value is used. If no gamma value is present, then the default of
      0.4545455 (more accurately, 5/11) is used; this is also used if this
      option is unticked.

   Display gamma
      Either the supplied gamma value or the default of 2.2 is used. (Useful
      if you have several images to convert whilst retaining their own gamma
      values.)

      Together with image gamma, this provides full control over the rendered
      image's gamma correction.

   Ignore transparency
      When ticked, do not use the alpha channel or other available
      transparency information - the resulting image will not have an alpha
      channel, and it may look a bit strange.

   Create a separate mask
      When ticked, a separate grey-scale sprite is created for the alpha
      channel. (This option is implied for greyscale PNGs.)

   Try to reduce mask
      When ticked, if the alpha channel can be reduced to a simple mask (as
      normally used in RISC OS sprites), it will be (even if the above option
      is ticked). (Images with simple masks have this kind of mask anyway.)

   Alpha channel is inverse
      Normally, the alpha channel scale ranges from 0 (transparent) to 255
      (opaque). This option tells Spr2Png to create an inverse mask, ie.
      using 0 as opaque.


  PNGs with 16 bits per channel (ie. 48-bit RGB, 16-bit grey) will always be
  reduced to 8 bits per channel (ie. 24-bit RGB, 8-bit grey).


The back ends
=============

  spr2png
  -------

  <Spr2Png$Dir>.spr2png [options] SRC DEST

    SRC			 The source file (sprite or Draw).

    DEST		 The destination file (PNG).

  General options:

    -i,			 The image will be interlaced using the ADAM7 method
    --interlace		 if this switch is present.

    -b,			 Specifies a suggested background colour of the form
    --background=COLOUR  &BBGGRR (as described above for the front end's save
			 box). If this is not present, no background colour
			 is defined.

    -x,			 Stores the number of pixels per metre (yes, metre,
    --dpi		 not inch, despite the name), calculated from the
			 mode information in the source sprite.
			 This information is used by png2spr.

    -X,			 Stores the height and width of one pixel, in metres,
    --pixel-size	 calculated from the mode information in the source
			 sprite.
			 This information is *NOT* used by png2spr. Both
			 --pixel-size and --dpi may be specified.

    -d,			 Set the number of dots per inch to the given
    --set-dpi=X[,Y]	 value(s). Implies --dpi.

  Sprite options:

    -a,			 If the sprite is 32-bit RGB, assume that it contains
    --alpha		 an alpha channel in the unused bits.
                         (Overridden by the presence of a mask or a mask
                         sprite.)

    -n,			 If an alpha channel is supplied, then it is assumed
    --inverse-alpha	 to be inverse, ie. 0 represents opaque rather than
			 transparent.
			 (Overridden by the presence of a Select alpha mask.)

  Draw and Artworks options (passed on to draw2spr):

    -S,			 Set the scale at which the drawing is rendered.
    --scale=X[,Y]	 (See below.)

    -m,	      -M,	 These two options work together to determine the
    --no-mask --no-blend masking and blending. (See below.)

    -R,			 Artworks rendering control. (See below.)
    --render=LEVEL

    Other options which are passed on: --background --trim --verbose

  Packing options:

    -c,			 If the mask or alpha channel is unused (fully opaque
    --check-mask	 image), ignore it. If it is 'simple' (only fully
			 transparent and opaque are used) and the image is
			 paletted, try to use a simple mask.
			 If the image is fully transparent...

    -t,			 Remove any transparent rows and columns from around
    --trim		 the edges of the sprite. If there's no mask, then
			 the background colour is treated as transparent.

    -r,			 Attempt to ensure that the resulting PNG is
    --reduce		 paletted. If the image has an alpha channel, it will
			 be used, resulting in paletted RGBA.

    -G,			 Perform extra greyscale tests - check whether only
    --check-grey	 greys are used in an image and convert it to
			 greyscale if so.

    -p,			 If the PNG can be represented as 1, 2 or 4bpp (ie.
    --pack-pixels	 is paletted and has sufficiently few palette
			 entries), then do so. This will usually /increase/
			 the size of the file. (Implies -r.)

    -s,			 Sort the palette such that the most often used
    --frequency-sort	 entries occur first. This can reduce the size of the
			 resulting PNG file slightly.
			 (This does not happen for greyscale PNGs.)

    -B,			 This option creates an sBIT chunk. This is
    --significant-bits=N recommended for 16bpp (15-bit colour) sprites, for
			 which you'll want to say "-B 5".

  Compression options:

    -f,			 Specifies, using a comma-separated list FLTR, a list
    --filter=FLTR	 of filter types to be tried when compressing the
			 image. These are 'none', 'sub', 'up', 'avg' and
			 'paeth'; 'all' may be used to select all five.
			 (Alternatively, you may use just the first letters,
			 omitting the commas.)
			 These may improve compression for some image types;
			 see the libpng documentation for more details.

    -w,			 This controls the compression algorithm's maximum
    --window-bits=NUM	 token length. It ranges between 9 and 15 bits;
			 higher values normally give better compression at a
			 speed cost. The default is 15.

    -z,			 This controls the compression strategy. Valid types
    --strategy=TYPE	 are "default" (0), "filtered" (1), "huffman" (2) and
			 "rle" (3); they can be referred to by number or
			 name. Default is normally best; Huffman and RLE are
			 fast but normally poorer.

    -0			 No compression.
    -1	  --fast	 Minimal compression; fast.
    -9	  --best	 Maximum compression; slow. This is the default.
			 Other values between 1 and 9 may be used.

  Renderer hints:

    -I,			 Specifies the rendering intent of the image. If TYPE
    --intent[=[+]TYPE]	 is 0 or 'default', no rendering intent is specified;
			 else sRGB colourspace is assumed, gamma and
			 chromaticity values are ignored, and the options are
			 1 to 4, or 'perceptual' (for pictures), 'relative'
			 (logos), 'saturation' (charts, graphs), and
			 'absolute' (proofing images). If TYPE is prefixed
			 with '+', default gamma and chromaticity values will
			 be written to the image for use by applications
			 which don't know about sRGB. See also [1].

    -g,			 Specifies the image's gamma correction value, ie.
    --gamma[=GAMMA]	 that required to properly display it. Acceptable
			 values are 0 to 10; if 0 or no argument is given,
			 then the default of 0.5 (ie. no correction with a
			 device gamma of 0.5) is used.

    -C,                  Specifies chromaticity information for the image.
    --chromaticity=LIST	 The parameter is eight comma-separated values,
			 handled as four pairs for the white point and the
			 red, green and blue channels. Value ranges are 0 to
			 1, and you may use "w", "r", "g" or "b" in place of
			 a value pair for a default setting.
			 (This is CIE x,y information. See also [2].)

  General options:

    -v,			 Be (more) verbose.
    --verbose


  draw2spr
  --------

  <Spr2Png$Dir>.draw2spr [options] SRC DEST

    SRC			 The source file (sprite or Draw).

    DEST		 The destination file (PNG).

    -s,			 Set the scale at which the drawing is rendered.
    --scale=X[,Y]	 This may be up to 10x along each axis; you may
			 specify one or two scaling factors.
			 Acceptable formats are simple, percentage and ratio.

    -t,			 Remove any transparent rows and columns from around
    --trim		 the edges of the sprite. If no mask is to be output,
			 then remove those same rows and columns since they
			 would otherwise have been masked out.

    -b,			 Specifies a background colour of the form &BBGGRR
    --background=COLOUR  (see above). If none is specified, then white is
			 used; however, a mask is always generated.

    -m,	      -M,	 These two options work together to determine the
    --no-mask --no-blend masking and blending as follows:
	      --no-alpha   -m -M  Effect
			   n  n  No mask, no anti-aliasing (see -R).
			   Y  n  Simple mask, no anti-aliasing (ditto).
			   n  Y  Background blended, always anti-aliased.
			   Y  Y  Full alpha channel, always anti-aliased.

    -n,			 If an alpha channel is created, then it is inverted,
    --inverse-alpha	 ie. 0 = opaque rather than transparent.

    -r,			 Artworks rendering control. The default is 11.0.
    --render=LEVEL	 (See the rendering level option in the front end.)

    -v,			 Be (more) verbose.
    --verbose


  png2spr
  -------

  <Spr2Png$Dir>.png2spr [options] SRC DEST

    -b,			 Use either the given colour, the image's colour or
    --background[=BGND]  white for the rendered PNG. The format is &BBGGRR
			 (as described above). If this is not present, then
			 an alpha channel will be generated (if no -M); else
			 the image will instead be background blended.
			 (Overrides -s and -c.)

    -g,			 Use either the given image gamma, the image's own
    --gamma[=GAMMA]	 gamma or 1/2.2. If not present, then the default of
			 1/2.2 is used.

    -d,			 Use the given display gamma correction, else 2.2.
    --display-gamma=GAMMA

    -M,			 Ignore transparency information, and don't generate
    --no-alpha		 an alpha channel. (Overrides -s and -c.)

    -s,			 Generate a greyscale sprite for the alpha channel.
    --separate-alpha	 (Implied for greyscale PNGs.)

    -c,			 If the alpha channel consists of fully transparent
    --check-mask	 and fully opaque, create a simple mask instead (and
			 not a separate alpha channel).
			 (Implied for paletted or greyscale PNGs with simple
			 transparency - ie. with a tRNS chunk.)

    -n,			 If the PNG contains an alpha channel (and it isn't
			 ignored or optimised out) then it is inverted, ie.
    --inverse-alpha	 ie. 0 = opaque rather than transparent.

    -f,			 Allow the sprite to have any values for its scale
    --free-dpi		 parameters. Without this, the values are clamped to
			 22.5 (rounded to 22), 45, 90 and 180, these being
			 the only values which RISC OS will handle natively.


  For all three programs, those short options which do not take arguments may
  be combined, eg. "-arfns" == "-a -r -fns". Those which do may be appended
  to the end of such a list.

  They also recognise --help and --version.


Sprite conversion information
-----------------------------

  Greyscale images are recognised by the standard 256-entry greyscale
  palette.

  Colour depth expansion is always performed from <8 bit to 8 bit, and from
  15 bit RGB or 32 bit CMYK to 32 bit RGB (the packed 24 bit RGB and JPEG
  formats are not handled). Further expansion will be performed from 8 bit
  colour to 32 bit RGB where:
   - a full alpha channel is used and cannot be reduced to a simple mask; or
   - there is a simple mask and all 256 colours are present in the image. (As
     in the GIF format, a simple mask occupies one logical colour.)

  Then, if a background colour is specified:
   - For 8 bit colour images using all 256 colours and with no mask, the
     nearest available palette entry will be chosen. Otherwise, a spare
     palette entry will be used.
   - For greyscale images, the grey nearest the specified RGB value will be
     used.
   - For 32 bit RGB images, no conversion is necessary; the colour is used as
     is.

  Some of this is controlled by various command line switches.


Draw and Artworks conversion information
----------------------------------------

  Draw and Artworks files are normally plotted in 32-bit RGB colour at 4
  times the specified scale) and are then reduced by a factor of 4 using a
  simple anti-aliasing algorithm. If a simple mask is requested, then they
  are simply plotted at the specified scale and no reduction is performed.

  There is no need to re-render the image, since it's possible to use the
  unused bits in each pixel to determine which are left untouched by the
  rendering process; this gives the mask. If an alpha channel is required,
  this is reduced as described above.

  Converting a large (in terms of the dimensions of the rendered image) file
  will use a lot of memory, although the back end can render Draw files in
  strips when memory is short.

  In Artworks files: deep sprites, text areas, replicated objects etc. won't
  be rendered. This is a limitation of the Artworks renderer modules.


PNG conversion information
--------------------------

  Deep sprites may be created.


Risc PC
-------

  Both spr2png and draw2spr prefer to use a dynamic area. The main advantage
  of doing so is in task-switching speed (although this is much less of an
  issue in RISC OS 3.8 and later). You'll notice it most when converting Draw
  and Artworks files.


Known bugs
==========

  Blends in Artworks files may cause draw2spr to become wedged, or possibly
  just take ages to render those files. Alt-Break should work; although
  nothing will be displayed, press Return anyway.

  (Whether this is the fault of draw2spr or ArtworksRenderer, I don't know.)


Browser display of PNGs
=======================

  Some browsers have problems with alpha channels when no background colour
  is specified for the image. The following is from my experience of various
  browsers:

   Arcweb 1.92
      Its somewhat basic PNG display code will default to something
      potentially very inappropriate (typically a black background).

   Browse 2.07
      No problems at all.

   Fresco 1.78F
      It totally ignores the alpha channel in paletted RGBA; otherwise, it
      uses a binary cutoff. (It has also been known to crash while loading
      several images.)

   Internet Explorer 4.01
      Seems to dislike PNGs...

   Internet Explorer 5
      It does not appear to be consistent in how it handles background
      colours across colour depths.

   Netscape Navigator 4.05
      It will render on a rectangle of the image's given background colour;
      if none is given, the alpha channel is ignored.

   Mozilla, Netscape 6 etc.
      These have PNG support as good as that of Browse.

  <URL:http://www.youmustbejoking.demon.co.uk/pngtest/> will show you how
  your browser copes with various PNGs with various options. (This is not an
  exhaustive test; it only tests colour depths and bKGD chunks.)


Licence
=======

Terms and conditions for copying, distribution and modification
---------------------------------------------------------------

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public Licence as published by the Free Software
Foundation; either version 2 of the Licence, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.  See the GNU General Public Licence for more
details.

You should have received a copy of the GNU General Public Licence along with
this program; if not, write to the Free Software Foundation, Inc., 59 Temple
Place, Suite 330, Boston, MA  02111-1307  USA


You will find the full text of the GPL version 2 in the Spr2Png source and
binary zip archives.


If you already have permission to distribute without source, that permission
still holds.


Credits & copyrights
====================

  libpng (the PNG library):
    Glenn Randers-Pehrson, Greg Roelofs, Guy Eric Schalnat and others
    <URL:ftp://ftp.freesoftware.com/pub/png/>

  zlib (the compression library):
    Jean-loup Gailly & Mark Adler
    <URL:ftp://ftp.cdrom.com/pub/infozip/zlib/>

  Draw to sprite:
    modified from Peter Hartley's Draw rendering code in InterGif
    <URL:http://utter.chaos.org.uk/~pdh/software/intergif.htm>

  Artworks to sprite:
    with help from Rob Davison and AWViewer.


  The spr2png and png2spr back-ends use libpng 1.2.8rel-5.1 and zlib
  1.2.3-11, built from source distributed by Debian.
    <URL:http://www.debian.org/>



Footnotes
=========

[1] sRGB ancillary chunk (standard RGB colour space):
  <URL:http://www.libpng.org/pub/png/spec/1.2/PNG-Chunks.html#C.sRGB>

[2] cHRM ancillary chunk (CIE x,y values):
  <URL:http://www.libpng.org/pub/png/spec/1.2/PNG-Chunks.html#C.cHRM>

Contact
=======

  Home page: <URL:http://www.youmustbejoking.demon.co.uk/>
  Home link: <URL:http://www.youmustbejoking.demon.co.uk/progs.graphics.html#spr2png>
  Email:     <URL:mailto:ds@youmustbejoking.demon.co.uk>
